# Installation

Prisma Client Rust's installation operates in a different way to most Rust projects.

`prisma-client-rust` contains the query builders, traits, and type definitions. Some of these - eg. `Direction` - may be used in your own code.

`prisma-client-rust-cli` contains the Prisma generator and access to the Prisma CLI, but does not provide an executable binary - this must be created yourself.

Prisma Client Rust requires a minimum Rust version of v1.62.0.

## Creating a CLI Binary

### Inside Your Crate

First, the main library and CLI package must be added to your project's Cargo.toml:

```toml
[dependencies]
prisma-client-rust = { git = "https://github.com/Brendonovich/prisma-client-rust", tag = "0.6.11" }
prisma-client-rust-cli = { git = "https://github.com/Brendonovich/prisma-client-rust", tag = "0.6.11" }
```

The generated client will need `serde`, so run `cargo add` to install it:

```
cargo add serde
```

You'll also need to make sure you're using edition 2021 of Rust.
```toml
[package]
# ... package stuff
edition = "2021"
```

The easiest way to create a binary to access the CLI through is by creating a `src/bin` folder if you don't already have one,
and inside it creating a file called something like `prisma.rs` (This will determine the name of your binary).
Inside this file put the following:

```rust
fn main() {
    prisma_client_rust_cli::run();
}
```

Technically, this is all that is required! Just run the following to access the CLI:

```bash
$ cargo run --bin <prisma binary name> -- <command>
```

import { Callout } from "nextra/components"

<Callout type="info">
If using Apple Silicon it is recommended to ensure Rosetta is installed, **even if you have installed it previously**.
Run `softwareupdate --install-rosetta --agree-to-license` to install it.
Not doing so may result in nondescript errors from Prisma's `query-engine` binary.
</Callout>

This isn't a very friendly command to run, though. Luckily Cargo allows us to define project-wide aliases for running commands! Create a folder at the root of your project called `.cargo` and inside it create a file `config.toml` containing the following:

```toml
[alias]
prisma = "run --bin <prisma binary name> --"
```

Now you can run `cargo prisma <command>` anywhere in your project to access the CLI!

This approach has some problems though:
1. `prisma-client-rust-cli` is included as a dependency in your crate, which is likely not desirable.
2. If your crate has errors during compilation then you aren't able to generate the client, since the CLI will also fail to compile!

Thankfully, there's a more reliable method:

### As a Workspace Crate

Move the CLI binary to a separate crate and configure your project to use
[Cargo workspaces](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html).
Below is a sample project structure that has one binary target in `src/main.rs`,
and a separate crate for the CLI named `prisma-cli` which is included in the workspace members of `Cargo.toml`.

```
Cargo.toml
.cargo/
    config.toml
src/
    main.rs
prisma-cli/
    Cargo.toml
    src/
        main.rs
```

For the above example,
`Cargo.toml` would include `prisma-client-rust` as a dependency as it is required by the generated file,
whereas `prisma-cli/Cargo.toml` would include `prisma-client-rust-cli` as a dependency,
and so the binary in `src/main.rs` would not be bundled with all the CLI code,
only the required library code.

You will also need to update the `cargo prisma` alias to run the new crate:

```toml
[alias]
prisma = "run -p <prisma crate name> --"
```

#### A Note on Virtual Workspaces

If the root `Cargo.toml` of your workspace has no `[package]` section (only a `[workspace]` section) then you are using a virtual workspace.

For Prisma Client Rust to compile properly, you'll need to instruct Cargo to use version 2 of the [feature resolver](https://doc.rust-lang.org/edition-guide/rust-2021/default-cargo-resolver.html).

```toml
[workspace]
# ... workspace stuff
resolver = "2"
```

This is not necessary for regular workspaces & single packages since they can use `edition = "2021"`, but virtual workspaces are special for some reason.

## Specifying Your Database

As of version 0.6.3,
Prisma Client Rust allows you to specify precisely which database connectors your project uses,
in order to avoid compiling the other connectors that Prisma supports.
This reduces compile times and binary sizes.

To start, set `default-features = false` for both `prisma-client-rust` and `prisma-client-rust-cli`.
Then add each database you would like to support as a feature for both crates.
The possible values are `postgresql`, `mysql`, `sqlite`, `mssql` and `mongodb`.

## Why is a CLI Binary Not Provided?

In older versions of Prisma Client Rust,
it was possible to `cargo install prisma-client-rust-cli` and have a global install of the CLI available to use at any time.
This had a major problem though: Versioning. Managing multiple projects that used different versions of Prisma Client Rust got very annoying very quickly,
plus it went against the recommmended installation instructions of Prisma Client
[JS](https://www.prisma.io/docs/getting-started/setup-prisma/add-to-existing-project/relational-databases-typescript-postgres),
[Go](https://github.com/prisma/prisma-client-go/blob/main/docs/quickstart.md),
and [Python](https://prisma-client-py.readthedocs.io/en/stable/#installing-prisma-client-python).

Unlike these three languages,
Rust (or more specifically Cargo) does not provide a method for executing binaries available inside dependencies.
Since installing a globally available binary was ruled out,
providing the CLI as a library was seen as the only other option,
plus personally I think that being able to run `cargo prisma <command>` is quite a nice experience and matches with clients in other languages.
